home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 5 / BBS in a Box -Volume V (BBS in a Box) (April 1992).iso / Files / Apple / Apple II TNs(Text).cpt / Apple II TNs(Text) / IIGS / TN.IIGS.051 < prev    next >
Encoding:
Text File  |  1989-11-15  |  6.6 KB  |  154 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIGS
  7. #51:    Reserving Memory for the Toolbox
  8.  
  9. Written by:    Eric Soldan                                       January 1989
  10.  
  11. This Technical Note discusses handling nearly-out-of-memory situations when 
  12. working with the IIGS tools.
  13. _____________________________________________________________________________
  14.  
  15.  
  16. Introduction
  17.  
  18. Running out of memory is a concern for most every application.  Working with 
  19. the Toolbox makes monitoring this situation a little more difficult since your 
  20. application is not the only one allocating memory.
  21.  
  22. Just waiting for an out-of-memory error is not necessarily adequate memory 
  23. management.  If you execute a NewHandle call successfully, there could be any 
  24. amount of memory left, from one byte to nearly all of it.  If there is not 
  25. much memory left, there might not be enough for the Toolbox.  A better scheme 
  26. of memory management would be to determine when the tools will need more 
  27. memory than is available.  You can treat this situation as "out-of-memory" as 
  28. well.
  29.  
  30. The Memory Manager calls to determine how much memory is available are 
  31. MaxBlock, FreeMem, and RealFreeMem.  However, none of these calls can give you 
  32. the complete picture.  FreeMem does not count purgeable handles.  RealFreeMem 
  33. does count purgeable handles, but memory may be very fragmented.  MaxBlock can 
  34. only tell you if you have enough RAM in a single block to complete a new 
  35. handle request, but it does not provide a good indication of when you do not 
  36. have enough, since memory may be fragmented.
  37.  
  38. Another way of determining if you have enough memory is with the NewHandle 
  39. call.  If you know that you are going to do a sequence of operations that will 
  40. not exceed N bytes of RAM, you can try a NewHandle call for that number of 
  41. bytes.  If it works, dispose the temporary handle and go for it.  Of course, 
  42. this may leave no memory available for the Toolbox, but you could fix this by 
  43. trying a NewHandle of size N+ToolboxNeeds.  The problem with this method is 
  44. that NewHandle is not the fastest Memory Manager call, and executing it 
  45. repeatedly can seriously degrade the performance of your application.
  46.  
  47.  
  48. A Suggested Method
  49.  
  50. Another method of checking for a nearly-out-of-memory condition is to have 
  51. your own purgeable handle just for this task.  You can use the purgeable 
  52. handle as a check for a nearly-out-of-memory situation.  If the handle has not 
  53. been purged, then you have plenty of memory for the Toolbox, and in the worst 
  54. case, the Toolbox will purge your handle if it needs the RAM.
  55.  
  56. The less often your purgeable handle gets purged, the better performance you 
  57. will probably get in nearly-out-of-memory situations.  Therefore, the purge 
  58. level of this handle should probably be 1.  (It might be better to have your 
  59. handle purged before several other purgeable handles which are of greater use 
  60. and could belong to you or others in the system.)  The check to see if a 
  61. handle has been purged is very fast.  If it has been purged, you will have to 
  62. see if it can be reallocated which is not a fast process, so the fewer times 
  63. the handle is purged, the faster the check will be and the better your 
  64. performance.  Unless you are in a nearly-out-of-memory situation, the handle 
  65. will not be purged at all, and you will have virtually no overhead for this 
  66. process.
  67.  
  68. This technique could be implemented as follows:
  69.  
  70. appStart              ;
  71. ;
  72. ;
  73. ;                     Somewhere at start, create a purgeable handle of size N,
  74. ;                     called "loMemHndl", purge level 1.
  75. ;
  76. ;
  77.                       rts
  78.  
  79. ******************
  80. ;            
  81. ;                     Here's an example of checking for nearly-out-of-memory:
  82. ;
  83.                       jsr    preCheckLoMem
  84.                       bcc    goForIt
  85.                       bcs    HandleError            ;Handle errors appropriately.
  86. goForIt               (_ToolboxCall[s])             ;Make as many as needed.
  87. ;
  88. ;                     Here you can make your toolbox calls.  Since you prechecked
  89. ;                     for nearly-out-of-memory conditions, you should have no memory
  90. ;                     errors at this point.
  91. ;
  92. ;                     You could also check after calls, as shown here:
  93. ;
  94.                       (_ToolboxCall)
  95.                       jsr    checkLoMem             ;Call this to see if low.
  96.                       bcc    noError
  97.                       bcs    HandleError            ;Take care of errors.
  98.  
  99. noError               jsr    lifeIsGood
  100.                       .
  101.                       .
  102.                       .
  103.                       rts
  104.  
  105. ******************
  106.  
  107. ******************
  108.  
  109. ;
  110. ;                     Here are some sample routines to check for the nearly-out-of-
  111. ;                     memory condition.
  112. ;
  113.  
  114. checkLoMem            bcs    retErr
  115. preCheckLoMem         lda    [loMemHndl]
  116.                       ldy    #2
  117.                       ora    [loMemHndl],y
  118.                       beq    gotPurged
  119.                       lda    #0
  120.                       clc
  121.                       rts
  122. gotPurged             (Try reallocating it into loMemHndl, purge level 1.)
  123.                       (If you can't, you will get a $0201 error.  You may wish to 
  124.                       return the $201 error, or you may wish to change it into
  125.                       your own error code.)
  126. ;
  127. retErr                rts                        ;This is a single exit point
  128.                                                  ;whether errors were present
  129.                                                  ;or not.
  130.  
  131. You can determine the size of this purgeable handle, but, like determining 
  132. what size stack is adequate for an application, there is no single "right" 
  133. answer.  There are different considerations for size of the purgeable handle 
  134. for each application, and these may change during the development process.  
  135. Use your best judgement.
  136.  
  137.  
  138. Conclusion
  139.  
  140. This Note is not meant to suggest that nearly-out-of-memory situations 
  141. require detection in this way, and there are many applications which 
  142. allocate enough RAM when they start (i.e., many paint programs) that if they 
  143. get the requested memory, they will not encounter out-of-memory situations 
  144. during that session.  There may also be other ways for a particular 
  145. application to detect and handle nearly-out-of-memory situations, but this 
  146. Note addresses this situation in a general way and offers only one solution 
  147. for your consideration.
  148.  
  149.  
  150. Further Reference:
  151. _____________________________________________________________________________
  152. o    Apple IIGS Toolbox Reference, Volumes 1 & 2
  153.  
  154.